.\" runlimit.8
.\" wcm, 2009.12.14 - 2011.02.08
.\" ===
.TH runlimit 8 "January 2013" "runtools-2.07" "runtools"
.SH NAME
runlimit \- run a program with new resource limits
.SH SYNOPSIS
.B runlimit [\-hV] [
.I opts
.B ]
.I program
.B [
.I args ...
.B ]
.SH DESCRIPTION
.B runlimit
sets up an environment with new resource limits as given by
.IR opts ,
then runs
.I program
with any additional
.IR args .
.PP
If
.I program
does not contain a ``/'' slash character,
.B runlimit
will perform a shell-like search for the executable using the
.B PATH
variable in the current environment.
.SH OPTIONS
For each of the following resource limit options in
.IR opts ,
.B runlimit
calls
.BR setrlimit (2)
to setup the corresponding soft resource limit.
Normally the argument to each option is a positive decimal integer.
An argument of
.RB ` = '
or
.RB `^'
may be given to set the soft limit equal to the current hard limit.
Any resource limit specified that is greater than its hard limit
is truncated to the hard limit.
.TP
.B \-E
Environment.
Resource parameters are scanned from the current environment in the form
.IR r = v ,
where
.I r
is any RLIMIT_* resource name as defined for
.BR getrlimit (2)
and described below,
and
.I v
is the value used to set the corresponding resource limit.
The
.B \-E
option may be combined with
.B \-F
or other options.
Any resource limit set with a command-line option,
or read from a file with the
.B \-F
option,
takes precedence over the environment.
.TP
.B \-F file
File-defined.
Resource limits are taken from
.IR file ,
a plain-text file with one or more non-empty lines of the form
.IR r = v ,
where
.I r
is any RLIMIT_* resource name as defined for
.BR getrlimit (2)
and described below,
and
.I v
is the value used to set the corresponding resource limit.
Empty lines and lines beginning with `#' are ignored.
Leading and trailing whitespace is trimmed from both
.I r
and
.IR v .
The
.B \-F
option may be combined with
.B \-E
or other options.
Any resource limit set with a command-line option
takes precedence over a file-defined limit.
.TP
.B \-a availmem
Total available memory (in bytes).
Resource parameter RLIMIT_AS and/or RLIMIT_VMEM (used synonymously).
.TP
.B \-c coresize
Maximum size of a core file (in bytes).
Resource parameter RLIMIT_CORE.
An argument of 0
will suppress core files.
.TP
.B \-d databytes
Maximum data segment (in bytes).
Resource parameter RLIMIT_DATA.
.TP
.B \-f filesize
Maximum size for any file that may be created (in bytes).
Resource parameter RLIMIT_FSIZE.
.TP
.B \-l lockbytes
Maximum memory that may be locked by
.BR mlock (2)
(in bytes).
Resource parameter RLIMIT_MEMLOCK.
.TP
.B \-m bytes
Combines the options
.B \-a \-d \-l
and
.B \-s
(in bytes).
.TP
.B \-o files
Maximum number of open files (in number of files).
Resource parameter RLIMIT_NOFILE.
.TP
.B \-p processes
Maximum number of processes per uid (in number of processes).
Resource parameter RLIMIT_NPROC.
.TP
.B \-r rssbytes
Maximum resident memory (in bytes).
Resource parameter RLIMIT_RSS.
.TP
.B \-s stackbytes
Maximum stack size (in bytes).
Resource parameter RLIMIT_STACK.
.B \-t secs
Maximum CPU time per process (in seconds).
Resource parameter RLIMIT_CPU.
.PP
.B runlimit
also provides the following standard
.BR runtools_intro (8)
options:
.TP
.B \-h
Help.
Print a brief usage message to stderr and exit.
.TP
.B \-V
Version.
Print the version number to stderr and exit.
.SH EXIT STATUS
.B runlimit
exits with one of the following values:
.TP
0
.I program
was invoked and completed successfully.
In this case,
the exit code is returned by the
.IR program ,
rather than by
.B runlimit
itself.
.TP
100
.B runlimit
failed because of a usage error,
such as an invalid command\-line option or argument.
In this case,
.B runlimit
prints a brief error message and usage help to stderr on exit.
.TP
111
.B runlimit
failed due to some system or resource error.
In this case,
.B runlimit
prints a brief diagnostic message to stderr on exit.
.TP
1\-127
.I program
was invoked and failed with its own non-zero exit status.
.SH CAVEATS
Not all resource limits are supported on all platforms.
.PP
(The source distribution includes a
.BR catlimits (8)
utility that will show the current resource limits,
indicating any that are not supported on the host platform.)
.SH AUTHOR
Wayne Marshall, http://b0llix.net/perp/
.SH SEE ALSO
.nh
.BR setrlimit (2),
.BR runtools_intro (8),
.BR runargs (8),
.BR runargv0 (8),
.BR runchoom (8),
.BR rundetach (8),
.BR rundeux (8),
.BR runenv (8),
.BR runfile (8),
.BR runlock (8),
.BR runpause (8),
.BR runsession (8),
.BR runtool (8),
.BR runtrap (8),
.BR runuid (8)
.\" EOF
